

                    The FreeTerm Terminal Emulator

                               Freeware
             (C) Tony Howat & Merlin Hughes 1995, 1996, 1997


0. Copyright

  The FreeTerm application is (C) Tony Howat 1995->7, with the SICKTerm
  terminal library (C) Merlin Hughes, but is released as freeware.
  This means that you may copy and distribute it, subject to certain
  conditions.

  Specifically, as an individual, you may only charge to cover the cost
  of distributing it, and you may not use it to make money directly or
  indirectly (by using it as an incentive to buy something else for
  example).

  Any company which wishes to include the program on a magazine disc or
  disc which will be sold *must* contact us to discuss arrangements.

  It is also imperative that anyone considering including FreeTerm in a
  internet suite of any sort (free or otherwise) contacts me (Tony Howat).

  Contact Tony Howat if you are unsure of how these terms affect you.

  FreeTerm should only be distributed with the whole contents of the
  original archive, with all files unmodified.

  SICKTerm makes use of ZapRedraw, (C) Dominic Symes 1994.
  The project was started by Tom Hughes, author of FreeNet.

  None of the authors accept any responsibility for any
  loss/damage/whatever resulting from the use of FreeTerm. It is
  supplied "as is".

1. Contents

  0.    ... Copyright
  1.    ... Contents
  2.    ... Introduction
  3.    ... Basic use of FreeTerm
  3.1   ... Downloading and Uploading text
  3.2   ... Disconnection
  3.3   ... Using finger
  3.4   ... The Host and Port Menus
  3.5   ... The FreeScript language
  3.5.1 ... Points to note
  3.5.2 ... Adding Scripts to the Hotlist
  3.6   ... CLI options
  3.7   ... The AutoRun Directory
  4.    ... Miscellaneous notes
  4.1   ... StrongARM Compatibility
  4.2   ... Programmers' guff
  4.3   ... Internationalisation
  5.    ... Contacting the authors

2. Introduction

  The FreeTerm application is a terminal emulator for use with any
  TCP/IP stack that supports the Acorn sockets interface. Currently
  that means either the Acorn TCP/IP stack, FreeNet or any of the
  commercial suites except Termite.

  Currently the application provides support for straightforward
  telnet and finger, and display sessions in a window which emulates
  a VT102 or VT52 series terminal. However, according to the beta
  testers it performs these basic functions rather well, and reliably,
  which is what matters.

3. Using FreeTerm

  Starting FreeTerm places an icon on the iconbar, and clicking on
  this provides a dialogue box with two writeable icons. The first
  of these takes the host name (or IP address), and the second
  the port number (or service name). Leaving the port
  number blank will cause it to default to the standard telnet
  port. Both the host and port writable icons are accompanied by
  pop up menus, and there is also a hot list on the icon bar
  menu. See the section 4 of this manual for details on how to set
  up these menus.

  Selecting certain ports (in this current version this will only
  occur with "finger") will cause the dialogue box to expand and
  display and extra arguments field for extra parameters needed
  to establish a certain kind of connection.

  Clicking on the connect button causes FreeTerm to establish a
  connection to the specified address, and then open a terminal
  window for the connection. For connections to the default telnet
  port, this window will default to character mode (where each
  character you type is transmitted straight away) if that is
  acceptable to the remote host, otherwise line mode is used.

3.1. Downloading and Uploading text.

  To send a file down the telnet connection drag it to the window. To
  save text from a telnet window highlight it, and drag it to a filer
  window.

  To download long chunks of text it is best to use the spooler, use
  the "Spool>Open" save as dialogue to locate your spoolfile and
  start recording. The spool may be paused, and selecting the
  "Spool>Strip" option will filter control codes from the output.
  When you have finished spooling click "Spool>Close"

  NB : FreeTerm only handles text downloads and uploads, ZModem
       transfers may be implemented in the future.

3.2. Disconnection

  Closing a terminal window will result in the connection to the
  remote host being dropped, whilst the remote host dropping an open
  connection will result in a message in the terminal window.

3.3. Using finger

  Finger is an internet service for finding out who is using a system,
  or finding out about users on a system. FreeTerm includes a finger
  client. To use it enter a hostname in the normal way and select
  "Finger" as the port, the connect window will grow an extra
  writeable icon, this is where you enter the finger string.

  The finger string specifies what information you want from the
  remote system. The most common types of finger strings are
  listed below.

  <Blank>  - An empty finger string lists all the users on a system.
  user     - Entering a valid username returns information on a
             specific user.

  ...you can use the @ character to finger via the system you are
  connecting to. So :

  @wibble.com     - lists the users on wibble.com via the system you
                    actually connected to.
  jack@wibble.com - gets information on the user 'jack' on wibble.com
                    via the system you actually connected to.

  You can use as many @'s as you need, but at most you should only
  need one if you ever need to finger through a firewall. 

  For more information on finger see RFC1288.

3.4. The host and port menus

  The connection dialogue features two writeable icons for entering
  the port name/number and the host you wish to connect to. Hostnames
  are usually fairly long, and on a local network with only a few
  hosts typing the same thing each time you wish to connect to a host
  soon becomes tiresome. FreeTerm v0.12 and later solve this by way
  of pop up menus, which are triggered by a button alongside each
  writeable icon. The host menu lists entries in the format :

  foo.bar.co.uk (Telnet)
  moo.cow.com (Finger)
  wibble.zonk.org
  ...

  The port name in brackets is the default port, not all entries may
  have a default port. Clicking on an entry in the menu fills in the
  writable fields in the connection box with the hostname and portname
  (if present), leaving you to press the "Connect" button.

  The icon bar hot list is exactly the same as the host menu, except
  that if you click on an entry with both a default port and host name
  the connection starts immediately. If the entry has no default port
  the connect dialogue box is displayed for you to enter a portname.

  The port menu simply lists frequently used portnames, clicking on an
  entry in the menu copies the portname to the writeable icon.

  The contents of the host menu/hotlist and port menu are read from
  configuration files in !FreeUser.Files.FreeTerm, namely HostList
  and PortList. The format of these files is explained in their
  comments.

  In older versions of FreeTerm you hand edit these files, you still
  can, but there is now a user interface in the configuration window
  (accessable from the iconbar 'Configure' option).

3.5. The FreeScript language

  The FreeScript language is basically designed to log you into
  machines automatically. For this reason it's very basic, although
  more commands and structures may be added in future.

  FreeScript files are text files of type "FScript" (&133).

  The best way to introduce their example, so here is a script I use
  to log into my university account and fire up pine (a mail/news
  reader) :

  # log into loki and start pine

  session telnet loki.brunel.ac.uk
    waitfor "ogin:"
    sendl   "cs96arh"
    waitfor "word:"
    sendl   "password"
    waitfor "loki%"
    sendl   "pine"
  sessionend

  Saving that as a file of type &133 and double clicking it will start
  FreeTerm and start the script. Obviously the password isn't correct.

  More usefully, here's a script to connect to archie at the Imperial
  college sunsite :

  # log into archie.doc.ic.ac.uk archie server

  session telnet archie.doc.ic.ac.uk
    waitfor "ogin:"
    sendl   "archie"
  sessionend

  Ok, that should make things fairly obvious. We can start multiple
  sessions in a script, so if I wanted to combine the scripts and log
  into archie after logging into my uni account I could use :

  session telnet loki.brunel.ac.uk
    waitfor "ogin:"
    ..blah..
    sendl   "pine"
    session telnet archie.doc.ic.ac.uk
      waitfor "ogin:"
      sendl   "archie"
    sessionend 
  sessionend

  ...or I could use the following if I just wanted to start connecting to
  archie at the same time as loki :

  session telnet loki.brunel.ac.uk
    waitfor "ogin:"
    ..blah..
    sendl   "pine"
  sessionend

  session telnet archie.doc.ic.ac.uk
    waitfor "ogin:"
    sendl   "archie"
  sessionend

  ...you can also use finger in a similar way to telnet...
  
  session finger mimac-03.brunel.ac.uk root
  sessionend

  A simple label jump mechanism is provided (allowing simple triggering)...

  session telnet wibble.org
    label   loop
    waitfor "hello"
    sendl   "hello to you too!"
    jump    loop
  sessionend 

  ...and finally there are a couple of commands I haven't mentioned :

  send "whatever"    is the same as sendl, but it does not do a linefeed
                     sequence after the string.
  sendf "file"       sends file - correct linefeed sequence is
                     inserted where needed.
  task "command"     runs command as a wimp task            
  waitforc           waits until a connection is established
  waitfordisconnect  waits for a session to disconnect
  title "text"       sets the window title of the terminal to "text".
                     This causes an error if no window is open for that
                     session.

  Like the rest of FreeTerm the script language is still in development,
  and will gain more commands and programming constructs as the project
  continues.

3.5.1. Points to note

  1) Once started session..endsession blocks are independant of each
     other.
  2) When a script is running keyboard input is not ignored.

3.5.2. Adding Scripts to the Hotlist

  To add a script to the hotlist simply copy it to the !FreeTerm.Scripts
  directory. This will result in the filename appearing after normal
  hotlist entries on the menu. You can change the name in the menu by
  including an alternative on the first line of a script prefixed by #$.

  eg. (one of the standard scripts)

  #$Archie (HENSA)
  #
  # Log into Archie server at HENSA
  # Tony Howat (xargle@eh.org)
  #
  
  session telnet archie.hensa.ac.uk
    title   "Archie at HENSA (login)"
    waitfor "ogin:"
    sendl   "archie"
    title   "Archie at HENSA"
  sessionend
  
  # end


3.6. CLI options

  -debug         Traces flow negociation to terminals as per pre-release
  -port <port>  
  -host <host>   These two options can be used to auto start a session
                 as soon as !FreeTerm is loaded.
  -args <...>    Used to specify arguments if you have specified a port
                 which makes use of them (ie finger)
  -nopop         No pop-up resolving messages, all problems reported via
                 full errors.
  -vtlie         Force FreeTerm to report itself to the remote
                 machine as a VT100 rather than a VT102 terminal. You
                 shouldn't need this unless you're working with
                 broken systems.
   -nofingerurl  FreeTerm doesn't interpret some finger URLs correctly, and
                 generally doesn't show the output as nicely as some web
                 browsers, so it can be prevented from responding to ArcWeb
                 & ANT finger URL broadcasts by using the new -nofingerurl
                 command line switch.           

3.7  The AutoRun Directory

  Files placed in the !FreeTerm.Config.AutoRun directory (or equivalent)
  will be run automatically on starting FreeTerm. I use this feature for
  auto starting my login script.

4. Miscellaneous notes

  If your FreeTerm session to a unix shell gets munged try 'reset'. The
  session should clear, and after a few <CR>'s you should get a normal
  prompt.

  The auto close check box in the configuration window will make _telnet_
  session windows close automatically if the remote end drops the
  connection.

  The window finder (off the icon bar menu) gives you a list of terminal
  windows open - click on one to bring it to the top.

  The VT100 keypad is useful on VMS systems etc. If you don't know what
  it is or how to use it you probably don't need it.

  If you use screens and have problems with extra newlines when a character
  on the last position on a line you should add "termcap LP" to .screenrc
  Read the screens man page for further info.

4.1. StrongARM Compatibility

  FreeTerm will not run properly on RISC OS 3.7 until the OS 3.7 patch
  has been installed. It can be downloaded from ART's web site.

  FreeTerm also works on the Acorn NC, which is thrilling if you own one.

4.2. Programmers' guff

  [note: you can launch sessions using ANTs URL protocol as of version 1.30
         - probably much easier, but this method is slightly more flexible]

  To trigger a session via a WIMP message send Message_FreeTermOp (&440A6).
  The data section should look as follows :

  length      type                      description
  4 bytes     int                       action code == 2
  8 bytes     empty
  64 bytes    null terminated string    port name/number
  80 bytes    null terminated string    destination address
  80 bytes    null terminated string    the arguments
  --------
  236 = total length

  This message is acked if recieved by FreeTerm. OSLib example in C
  follows :

  #include "oslib:user.wimp.h"
  #include "kernel.h"
  #include <string.h>
  
  #define Message_FreeTermOp 0x440a6
    
  typedef struct {
    int action;              /* action code */
    int spare1;
    int spare2;
    char port[64];
    char dest[80];
    char args[80];
  } freeterm_openmsg;
  
  int main(void)
  {
    int    wimpver;
    wimp_t mytaskhandle;
    static wimp_block block;
    wimp_message ms;
    freeterm_openmsg *fom=(freeterm_openmsg *)&(ms.data);
  
    mytaskhandle = wimp_initialise(310,"FreeTerm Test",(void *)-1,&wimpver);
  
    ms.action=Message_FreeTermOp;
    ms.my_ref=0;
    ms.your_ref=1;
    ms.sender=mytaskhandle;
    strcpy(fom->port,"finger");
    strcpy(fom->dest,"g7lzb.ampr.org");
    strcpy(fom->args,"g7lzb");
    fom->action=2;
    ms.size=sizeof(freeterm_openmsg);
    
    wimp_send_message(wimp_USER_MESSAGE,&ms,0);
  
    xwimp_close_down(mytaskhandle);
    return 0;
  }

  The Config.Fonts file is in the format:
    Name                               (string - to appear in menus)
  then
    zap b.m.                           (literal string)
    <TermFonts$Dir>.BitMaps.X.10x20    (string)
  or (for those who are prepared to tweak parameters for a while)
    zap a.a.                           (literal string)
    corpus.medium                      (RISC-OS font name)
    10                                 Point size
    16                                 Width of font
    12                                 Height of font
    0                                  X offset (usually 0)
    8                                  Y offset (usually >0)
  or
    zap b.m. dir
    <TermFonts$Dir>.BitMaps.CX         (Directory to find set of zap fonts)

4.3. Internationalisation

  I would be extactic if people could provide me with resources for
  different languages to be made available alongside the standard
  FreeTerm distribution. e-mail them UUCoded to xargle@eh.org

4.4. Credits

  Programming :
     Tom Hughes (tom@compton.demon.co.uk) started the project.
     Tony Howat (xargle@eh.org) continued it.
     Merlin Hughes (hughesm@cs.unc.edu) wrote the terminal emulator.

  Thanks to :
     Dominic Symes (dominic.symes@armltd.co.uk) for ZapRedraw.
     Stewart Brodie (s.n.brodie@ecs.soton.ac.uk) for help with ArcWeb.
     Ben Summers for help with the ColourPicker, and those on
     comp.sys.acorn.programmer for sorting me out on the occasions when
     I saw fit to ask particularly dumb questions.
     Graham Allen for his help in sadistic terminal emulator abuse.
     Pineapple Software for allocating the FreeScript filetype so promptly. 
     Richard Atterer <atterer@augsburg.baynet.de> designed the curreny
     default sprite set, and provided the German resources.

  ..and thanks to the beta testers for their helpful comments and
    suggestions.

5. Contacting the author(s)

  Any queries on the subject of FreeNet in general should be sent
  to the original author of FreeTerm, Tom Hughes, who can be contacted by
  email at freenet@compton.demon.co.uk, or by snail mail at:

      Tom Hughes
      5 Lampits
      Hoddesdon
      Hertfordshire
      EN11 8EH

  Those with basic configuration problems would be best served by the
  comp.sys.acorn.networking newsgroup.

  Development of FreeTerm is being undertaken by Tony Howat, so
  suggestions for enhancements and bug reports should be sent to him
  by email to xargle@eh.org, or by snail mail at:

      Tony Howat
      12 Dover Road
      Birkdale
      Southport
      Merseyside
      PR8 4SY

  (mail will be forwarded to my university address during term time)

  Only FreeTerm _specific_ queries should be sent to this address, I
  can't help on a more general level. My setup is uniquely strange and
  flakey :)

  If you are so enamoured with FreeTerm that you feel that you may like
  to buy the authors a pint or three money is welcome at the above
  address, it will be split fairly. (We're both impoverished students,
  and so couldn't miss the chance of a beer or two for our trouble!)

  FreeTerm has a web page which should now available from the
  20-20 Software home page. Point your browser at
  http://www.xargle.demon.co.uk/2020


